Image

Includes an external Graphic. Allowed graphic formats are PDF (.pdf), PNG (.png) and JPEG (.jpg). Other file types might be possible with external converters. See below for a limitation on the number of included PDF files.

Child elements

Value

Parent elements

A, B, Case, Clip, Color, Fontface, ForAll, Frame, I, Li, Loop, NoBreak, Otherwise, Overlay, Paragraph, PlaceObject, Position, Span, Td, Text, Transformation, U, URL, Until, While

Attributes

bleed (optional, since version 2.9.5)

Should the image size increase by the amount of bleed setting (Options)?

auto

If the image touches a paper edge, extend the image in that direction.

no

Do not extend the image.

class (text, optional, since version 2.5.11)

CSS class for this element.

clip (optional)

When yes, the image keeps its aspect ratio if both width and hight is given. To be able to fit the image into the given dimensions, the image gets clipped.

yes

Keep the aspect ratio and cut off left/right or top/bottom edges.

no

Distort the image to make it fit in the given area.

description (text, optional, since version 4.19.8)

An alternative text for accessibility

dpiwarn (number, optional)

Warn if the image gets lower resolution than given.

fallback (optional, since version 2.3.77)

The filename of the replacement image if the file is not found. If none given, a red 'file not found' image will gets displayed.

file (text, optional)

Filename of the image. Can be a file in the search path, an absolute file name, a file-URI for absolute paths (e.g. file:///path/to/image.pdf) or a location on the web (http, https).

height (number or length, optional)

Image height. One of 'auto' (default, take image width), length (such as '3cm') or number (in grid cells).

id (text, optional, since version 2.5.11)

CSS id for this element.

imageshape (yes or no, optional, since version 4.9.8)

Try to load an image shape. Defaults to no.

imagetype (optional, since version 3.9.1)

Set the converter to be used for the enclosed image (if any).

margin-bottom (length, optional, since version 4.13.13)

Extra space at the bottom of the image.

margin-left (length, optional, since version 4.13.13)

Extra space at the left of the image.

margin-right (length, optional, since version 4.13.13)

Extra space at the right of the image.

margin-top (length, optional, since version 4.13.13)

Extra space at the top of the image.

maxheight (number or length, optional)

The maximum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

maxwidth (number or length, optional)

The maximum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

minheight (number or length, optional)

The minimum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

minwidth (number or length, optional)

The minimum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

opacity (number, optional, since version 4.3.15)

Set image opacity (0-100, 100=fully opaque).

padding (length, optional, since version 2.9.5)

Set padding for all four sides.

padding-bottom (length, optional, CSS property: padding-bottom, since version 2.5.11)

Set the inner distance (width between contents and the border) to the bottom edge.

padding-left (length, optional, CSS property: padding-left, since version 2.5.11)

Set the inner distance (width between contents and the border) to the left edge.

padding-right (length, optional, CSS property: padding-right, since version 2.5.11)

Set the inner distance (width between contents and the border) to the right edge.

padding-top (length, optional, CSS property: padding-top, since version 2.5.11)

Set the inner distance (width between contents and the border) to the top edge.

page (number, optional)

The page number from the PDF. Default is 1 (include the first page).

parent (text, optional, since version 4.19.8)

The id of the parent structure element for tagged PDF

role (optional, since version 4.19.23)

The role for PDF/UA (accessibility, tagged PDF)

rotate (number, optional)

Rotate the image in steps of 90°. The amount of movement is defined by the specified angle; if positive, the movement will be clockwise, if negative, it will be counter-clockwise.

stretch (yes or no, optional, since version 4.3.8)

Stretch image until one of maximum width and maximum height is reached. Useful if images should be as large as possible but should not use more than the given space.

visiblebox (optional)

The PDF box that represents the visible area of the included image. Default is “cropbox”.

artbox

Use the artbox as the visible area. The artbox is usually not contained in a PDF.

bleedbox

Use the bleedbox of the included PDF.

cropbox

Use the cropbox of the included PDF (default).

mediabox

Use the mediabox of the included PDF. This is the largest box.

trimbox

Use the trimbox of the includes PDF. The trimbox is the final paper size. For example, the trim box of an A4 PDF is 210mm x 297mm.

width (number or length, optional)

Image width. One of 'auto' (default, take image width), '100%' (whole area width), length (such as '3cm') or number (in grid cells).

Remarks

The values of the attributes naturalsize and maxsize can be ‘artbox’, ‘bleedbox’, ‘cropbox’, ‘mediabox’ and ‘trimbox’. These two values are used to enlarge the image for the bleed. In the second example below the designated view port of the image is defined in the artbox, but the image has a larger area (the cropbox) that is used for bleeding.

Example

<Record element="productdata">
  <PlaceObject column="{ $column }">
    <Image width="10" file="{ string(.) }"/>
  </PlaceObject>
</Record>

Takes the file name of the image from the contents of the current element in the data file (here: productdata). Sample data XML:

<productdata>image.pdf</productdata>

The following example reads a pdf file, extracts a page and make the given artbox (should be set in the pdf file) the width of 210mm. If we have an area in the pdf that is larger than the artbox, it will be larger than the given size.

<Record element="data">
  <PlaceObject column="0mm" row="0mm">
    <Image width="210mm" file="catalog.pdf" page="132" naturalsize="artbox"/>
  </PlaceObject>
</Record>

Info

The number of pages in a PDF file can be determined with the XPath function sd:number-of-pages(<filename or URI>).

Attention. The number of PDF files that can be included in a document is limited. This limit can be increased in is system dependant. On Mac OS X it can be queried with ulimit -a and set for example with ulimit -n 1024.

See also

The section about <Image> in the basics chapter, File organization